GattServer.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_SERVER_H__
00018 #define __GATT_SERVER_H__
00019 
00020 #include "Gap.h"
00021 #include "GattService.h"
00022 #include "GattAttribute.h"
00023 #include "GattServerEvents.h"
00024 #include "GattCallbackParamTypes.h"
00025 #include "CallChainOfFunctionPointersWithContext.h"
00026 
00027 class GattServer {
00028 public:
00029     /* Event callback handlers. */
00030     typedef void (*EventCallback_t)(GattAttribute::Handle_t attributeHandle);
00031     typedef void (*ServerEventCallback_t)(void);                    /**< independent of any particular attribute */
00032 
00033 protected:
00034     GattServer() :
00035         serviceCount(0),
00036         characteristicCount(0),
00037         dataSentCallChain(),
00038         dataWrittenCallChain(),
00039         dataReadCallChain(),
00040         updatesEnabledCallback(NULL),
00041         updatesDisabledCallback(NULL),
00042         confirmationReceivedCallback(NULL) {
00043         /* empty */
00044     }
00045 
00046     /*
00047      * The following functions are meant to be overridden in the platform-specific sub-class.
00048      */
00049 public:
00050 
00051     /**
00052      * Add a service declaration to the local server ATT table. Also add the
00053      * characteristics contained within.
00054      */
00055     virtual ble_error_t addService(GattService &service) {
00056         /* avoid compiler warnings about unused variables */
00057         (void)service;
00058 
00059         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00060     }
00061 
00062     /**
00063      * Read the value of a characteristic from the local GattServer
00064      * @param[in]     attributeHandle
00065      *                  Attribute handle for the value attribute of the characteristic.
00066      * @param[out]    buffer
00067      *                  A buffer to hold the value being read.
00068      * @param[in/out] lengthP
00069      *                  Length of the buffer being supplied. If the attribute
00070      *                  value is longer than the size of the supplied buffer,
00071      *                  this variable will hold upon return the total attribute value length
00072      *                  (excluding offset). The application may use this
00073      *                  information to allocate a suitable buffer size.
00074      *
00075      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
00076      */
00077     virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) {
00078         /* avoid compiler warnings about unused variables */
00079         (void)attributeHandle;
00080         (void)buffer;
00081         (void)lengthP;
00082 
00083         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00084     }
00085 
00086     /**
00087      * Read the value of a characteristic from the local GattServer
00088      * @param[in]     connectionHandle
00089      *                  Connection Handle.
00090      * @param[in]     attributeHandle
00091      *                  Attribute handle for the value attribute of the characteristic.
00092      * @param[out]    buffer
00093      *                  A buffer to hold the value being read.
00094      * @param[in/out] lengthP
00095      *                  Length of the buffer being supplied. If the attribute
00096      *                  value is longer than the size of the supplied buffer,
00097      *                  this variable will hold upon return the total attribute value length
00098      *                  (excluding offset). The application may use this
00099      *                  information to allocate a suitable buffer size.
00100      *
00101      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
00102      *
00103      * @note This API is a version of above with an additional connection handle
00104      *     parameter to allow fetches for connection-specific multivalued
00105      *     attributes (such as the CCCDs).
00106      */
00107     virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
00108         /* avoid compiler warnings about unused variables */
00109         (void)connectionHandle;
00110         (void)attributeHandle;
00111         (void)buffer;
00112         (void)lengthP;
00113 
00114         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00115     }
00116 
00117     /**
00118      * Update the value of a characteristic on the local GattServer.
00119      *
00120      * @param[in] attributeHandle
00121      *              Handle for the value attribute of the Characteristic.
00122      * @param[in] value
00123      *              A pointer to a buffer holding the new value
00124      * @param[in] size
00125      *              Size of the new value (in bytes).
00126      * @param[in] localOnly
00127      *              Should this update be kept on the local
00128      *              GattServer regardless of the state of the
00129      *              notify/indicate flag in the CCCD for this
00130      *              Characteristic? If set to true, no notification
00131      *              or indication is generated.
00132      *
00133      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
00134      */
00135     virtual ble_error_t write(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) {
00136         /* avoid compiler warnings about unused variables */
00137         (void)attributeHandle;
00138         (void)value;
00139         (void)size;
00140         (void)localOnly;
00141 
00142         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00143     }
00144 
00145     /**
00146      * Update the value of a characteristic on the local GattServer. A version
00147      * of the same as above with connection handle parameter to allow updates
00148      * for connection-specific multivalued attributes (such as the CCCDs).
00149      *
00150      * @param[in] connectionHandle
00151      *              Connection Handle.
00152      * @param[in] attributeHandle
00153      *              Handle for the value attribute of the Characteristic.
00154      * @param[in] value
00155      *              A pointer to a buffer holding the new value
00156      * @param[in] size
00157      *              Size of the new value (in bytes).
00158      * @param[in] localOnly
00159      *              Should this update be kept on the local
00160      *              GattServer regardless of the state of the
00161      *              notify/indicate flag in the CCCD for this
00162      *              Characteristic? If set to true, no notification
00163      *              or indication is generated.
00164      *
00165      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
00166      */
00167     virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) {
00168         /* avoid compiler warnings about unused variables */
00169         (void)connectionHandle;
00170         (void)attributeHandle;
00171         (void)value;
00172         (void)size;
00173         (void)localOnly;
00174 
00175         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00176     }
00177 
00178     /**
00179      * Determine the updates-enabled status (notification/indication) for the current connection from a characteristic's CCCD.
00180      *
00181      * @param       characteristic
00182      *                The characteristic
00183      * @param[out]  enabledP
00184      *                Upon return, *enabledP is true if updates are enabled, else false.
00185      *
00186      * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise.
00187      */
00188     virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP) {
00189         /* avoid compiler warnings about unused variables */
00190         (void)characteristic;
00191         (void)enabledP;
00192 
00193         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00194     }
00195 
00196     /**
00197      * Determine the connection-specific updates-enabled status (notification/indication) from a characteristic's CCCD.
00198      *
00199      * @param       connectionHandle
00200      *                The connection handle
00201      * @param[out]  enabledP
00202      *                Upon return, *enabledP is true if updates are enabled, else false.
00203      *
00204      * @param  characteristic
00205      *           The characteristic
00206      *
00207      * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise.
00208      */
00209     virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) {
00210         /* avoid compiler warnings about unused variables */
00211         (void)connectionHandle;
00212         (void)characteristic;
00213         (void)enabledP;
00214 
00215         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
00216     }
00217 
00218     /**
00219      * A virtual function to allow underlying stacks to indicate if they support
00220      * onDataRead(). It should be overridden to return true as applicable.
00221      */
00222     virtual bool isOnDataReadAvailable() const {
00223         return false; /* Requesting action from porter(s): override this API if this capability is supported. */
00224     }
00225 
00226     /*
00227      * APIs with non-virtual implementations.
00228      */
00229 public:
00230     /**
00231      * Add a callback for the GATT event DATA_SENT (which is triggered when
00232      * updates are sent out by GATT in the form of notifications).
00233      *
00234      * @Note: it is possible to chain together multiple onDataSent callbacks
00235      * (potentially from different modules of an application) to receive updates
00236      * to characteristics.
00237      *
00238      * @Note: it is also possible to setup a callback into a member function of
00239      * some object.
00240      */
00241     void onDataSent(void (*callback)(unsigned count)) {dataSentCallChain.add(callback);}
00242     template <typename T>
00243     void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
00244         dataSentCallChain.add(objPtr, memberPtr);
00245     }
00246 
00247     /**
00248      * Setup a callback for when an attribute has its value updated by or at the
00249      * connected peer. For a peripheral, this callback triggered when the local
00250      * GATT server has an attribute updated by a write command from the peer.
00251      * For a Central, this callback is triggered when a response is received for
00252      * a write request.
00253      *
00254      * @Note: it is possible to chain together multiple onDataWritten callbacks
00255      * (potentially from different modules of an application) to receive updates
00256      * to characteristics. Many services, such as DFU and UART add their own
00257      * onDataWritten callbacks behind the scenes to trap interesting events.
00258      *
00259      * @Note: it is also possible to setup a callback into a member function of
00260      * some object.
00261      */
00262     void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {dataWrittenCallChain.add(callback);}
00263     template <typename T>
00264     void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
00265         dataWrittenCallChain.add(objPtr, memberPtr);
00266     }
00267 
00268     /**
00269      * Setup a callback to be invoked on the peripheral when an attribute is
00270      * being read by a remote client.
00271      *
00272      * @Note: this functionality may not be available on all underlying stacks.
00273      * You could use GattCharacteristic::setReadAuthorizationCallback() as an
00274      * alternative.
00275      *
00276      * @Note: it is possible to chain together multiple onDataRead callbacks
00277      * (potentially from different modules of an application) to receive updates
00278      * to characteristics. Services may add their own onDataRead callbacks
00279      * behind the scenes to trap interesting events.
00280      *
00281      * @Note: it is also possible to setup a callback into a member function of
00282      * some object.
00283      *
00284      * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
00285      *         else BLE_ERROR_NONE.
00286      */
00287     ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
00288         if (!isOnDataReadAvailable()) {
00289             return BLE_ERROR_NOT_IMPLEMENTED;
00290         }
00291 
00292         dataReadCallChain.add(callback);
00293         return BLE_ERROR_NONE;
00294     }
00295     template <typename T>
00296     ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
00297         if (!isOnDataReadAvailable()) {
00298             return BLE_ERROR_NOT_IMPLEMENTED;
00299         }
00300 
00301         dataReadCallChain.add(objPtr, memberPtr);
00302         return BLE_ERROR_NONE;
00303     }
00304 
00305     /**
00306      * Setup a callback for when notifications/indications are enabled for a
00307      * characteristic on the local GattServer.
00308      */
00309     void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;}
00310 
00311     /**
00312      * Setup a callback for when notifications/indications are disabled for a
00313      * characteristic on the local GattServer.
00314      */
00315     void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;}
00316 
00317     /**
00318      * Setup a callback for when the GATT server receives a response for an
00319      * indication event sent previously.
00320      */
00321     void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;}
00322 
00323     /* Entry points for the underlying stack to report events back to the user. */
00324 protected:
00325     void handleDataWrittenEvent(const GattWriteCallbackParams *params) {
00326         if (dataWrittenCallChain.hasCallbacksAttached()) {
00327             dataWrittenCallChain.call(params);
00328         }
00329     }
00330 
00331     void handleDataReadEvent(const GattReadCallbackParams *params) {
00332         if (dataReadCallChain.hasCallbacksAttached()) {
00333             dataReadCallChain.call(params);
00334         }
00335     }
00336 
00337     void handleEvent(GattServerEvents::gattEvent_e  type, GattAttribute::Handle_t attributeHandle) {
00338         switch (type) {
00339             case GattServerEvents::GATT_EVENT_UPDATES_ENABLED:
00340                 if (updatesEnabledCallback) {
00341                     updatesEnabledCallback(attributeHandle);
00342                 }
00343                 break;
00344             case GattServerEvents::GATT_EVENT_UPDATES_DISABLED:
00345                 if (updatesDisabledCallback) {
00346                     updatesDisabledCallback(attributeHandle);
00347                 }
00348                 break;
00349             case GattServerEvents::GATT_EVENT_CONFIRMATION_RECEIVED:
00350                 if (confirmationReceivedCallback) {
00351                     confirmationReceivedCallback(attributeHandle);
00352                 }
00353                 break;
00354             default:
00355                 break;
00356         }
00357     }
00358 
00359     void handleDataSentEvent(unsigned count) {
00360         if (dataSentCallChain.hasCallbacksAttached()) {
00361             dataSentCallChain.call(count);
00362         }
00363     }
00364 
00365 protected:
00366     uint8_t serviceCount;
00367     uint8_t characteristicCount;
00368 
00369 private:
00370     CallChainOfFunctionPointersWithContext<unsigned>                         dataSentCallChain;
00371     CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *>  dataWrittenCallChain;
00372     CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *>   dataReadCallChain;
00373     EventCallback_t                                                         updatesEnabledCallback;
00374     EventCallback_t                                                         updatesDisabledCallback;
00375     EventCallback_t                                                         confirmationReceivedCallback;
00376 
00377 private:
00378     /* disallow copy and assignment */
00379     GattServer(const GattServer &);
00380     GattServer& operator=(const GattServer &);
00381 };
00382 
00383 #endif // ifndef __GATT_SERVER_H__