YuLin Jiang / nRF51BLE_API

BLE_API for nRF51

Fork of BLE_API by Bluetooth Low Energy

public/CallChainOfFunctionPointersWithContext.h@118:620d28e7a1ba, 2014-09-22 (annotated)

Committer:
Rohit Grover
Date:
Mon Sep 22 10:59:09 2014 +0100
Revision:
118:620d28e7a1ba
Child:
126:fdebe4d5d62f
Release 0.2.0

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



Highlights:

  Introducing standard services to simplify applications.

  Add support for over-the-air firmware updates.



Features

~~~~~~~~



- This release introduces 'templates' for common services such as heart-rate,

  battery-level, device-info, UART, device-firmware-update etc. These services

  take the shape of class declarations within header files aggregated under a

  new folder called 'services/'. These service-classes provide a high-level

  API hopefully easing the burden of developing BLE applications. The

  underlying APIs to work with characteristics and services are still

  available to allow greater control if needed. We expect to grow the

  supported services to include all SIG defined BLE profiles.



- WriteCallbackParams now includes the characteristic's value-attribute

  handle; this changes the signature of onDataWritten().



- BLEDevice::onDataWritten() now allows chaining of callbacks--this means that

  it is possible to chain together multiple onDataWritten callbacks

  (potentially from different modules of an application) to receive updates to

  characteristics. Many services, such as DFU and UART add their own

  onDataWritten callbacks behind the scenes to trap interesting events. It is

  also possible to chain callbacks to functions within objects.



- Added the following expectation for GattCharacteristic: If valuePtr ==

  NULL, initialLength == 0, and properties == READ for the value attribute of

  a characteristic, then that particular characteristic may be considered

  optional and dropped while instantiating the service with the underlying BLE

  stack.



- Introducing the typedef GattAttribute::Handle_t to capture Attribute handles.



Bugfixes

~~~~~~~~



None.



Compatibility

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



The signature of onDataWritten() has seen a change; so application programs

using this new version of the BLE API will need minor modifications. Please

refer to sample programs under BLE team page.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Rohit Grover 118:620d28e7a1ba 1 /* mbed Microcontroller Library
Rohit Grover 118:620d28e7a1ba 2 * Copyright (c) 2006-2013 ARM Limited
Rohit Grover 118:620d28e7a1ba 3 *
Rohit Grover 118:620d28e7a1ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
Rohit Grover 118:620d28e7a1ba 5 * you may not use this file except in compliance with the License.
Rohit Grover 118:620d28e7a1ba 6 * You may obtain a copy of the License at
Rohit Grover 118:620d28e7a1ba 7 *
Rohit Grover 118:620d28e7a1ba 8 * http://www.apache.org/licenses/LICENSE-2.0
Rohit Grover 118:620d28e7a1ba 9 *
Rohit Grover 118:620d28e7a1ba 10 * Unless required by applicable law or agreed to in writing, software
Rohit Grover 118:620d28e7a1ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
Rohit Grover 118:620d28e7a1ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Rohit Grover 118:620d28e7a1ba 13 * See the License for the specific language governing permissions and
Rohit Grover 118:620d28e7a1ba 14 * limitations under the License.
Rohit Grover 118:620d28e7a1ba 15 */
Rohit Grover 118:620d28e7a1ba 16 #ifndef MBED_CALLCHAIN_OF_FUNCTION_POINTERS_WITH_CONTEXT_H
Rohit Grover 118:620d28e7a1ba 17 #define MBED_CALLCHAIN_OF_FUNCTION_POINTERS_WITH_CONTEXT_H
Rohit Grover 118:620d28e7a1ba 18
Rohit Grover 118:620d28e7a1ba 19 #include <string.h>
Rohit Grover 118:620d28e7a1ba 20 #include "FunctionPointerWithContext.h"
Rohit Grover 118:620d28e7a1ba 21
Rohit Grover 118:620d28e7a1ba 22 namespace mbed {
Rohit Grover 118:620d28e7a1ba 23
Rohit Grover 118:620d28e7a1ba 24 /** Group one or more functions in an instance of a CallChainOfFunctionPointersWithContext, then call them in
Rohit Grover 118:620d28e7a1ba 25 * sequence using CallChainOfFunctionPointersWithContext::call(). Used mostly by the interrupt chaining code,
Rohit Grover 118:620d28e7a1ba 26 * but can be used for other purposes.
Rohit Grover 118:620d28e7a1ba 27 *
Rohit Grover 118:620d28e7a1ba 28 * Example:
Rohit Grover 118:620d28e7a1ba 29 * @code
Rohit Grover 118:620d28e7a1ba 30 * #include "mbed.h"
Rohit Grover 118:620d28e7a1ba 31 *
Rohit Grover 118:620d28e7a1ba 32 * CallChainOfFunctionPointersWithContext<void *> chain;
Rohit Grover 118:620d28e7a1ba 33 *
Rohit Grover 118:620d28e7a1ba 34 * void first(void *context) {
Rohit Grover 118:620d28e7a1ba 35 * printf("'first' function.\n");
Rohit Grover 118:620d28e7a1ba 36 * }
Rohit Grover 118:620d28e7a1ba 37 *
Rohit Grover 118:620d28e7a1ba 38 * void second(void *context) {
Rohit Grover 118:620d28e7a1ba 39 * printf("'second' function.\n");
Rohit Grover 118:620d28e7a1ba 40 * }
Rohit Grover 118:620d28e7a1ba 41 *
Rohit Grover 118:620d28e7a1ba 42 * class Test {
Rohit Grover 118:620d28e7a1ba 43 * public:
Rohit Grover 118:620d28e7a1ba 44 * void f(void *context) {
Rohit Grover 118:620d28e7a1ba 45 * printf("A::f (class member).\n");
Rohit Grover 118:620d28e7a1ba 46 * }
Rohit Grover 118:620d28e7a1ba 47 * };
Rohit Grover 118:620d28e7a1ba 48 *
Rohit Grover 118:620d28e7a1ba 49 * int main() {
Rohit Grover 118:620d28e7a1ba 50 * Test test;
Rohit Grover 118:620d28e7a1ba 51 *
Rohit Grover 118:620d28e7a1ba 52 * chain.add(second);
Rohit Grover 118:620d28e7a1ba 53 * chain.add_front(first);
Rohit Grover 118:620d28e7a1ba 54 * chain.add(&test, &Test::f);
Rohit Grover 118:620d28e7a1ba 55 * chain.call();
Rohit Grover 118:620d28e7a1ba 56 * }
Rohit Grover 118:620d28e7a1ba 57 * @endcode
Rohit Grover 118:620d28e7a1ba 58 */
Rohit Grover 118:620d28e7a1ba 59
Rohit Grover 118:620d28e7a1ba 60 template <typename ContextType>
Rohit Grover 118:620d28e7a1ba 61 class CallChainOfFunctionPointersWithContext {
Rohit Grover 118:620d28e7a1ba 62 public:
Rohit Grover 118:620d28e7a1ba 63 typedef FunctionPointerWithContext<ContextType>* pFunctionPointerWithContext_t;
Rohit Grover 118:620d28e7a1ba 64
Rohit Grover 118:620d28e7a1ba 65 public:
Rohit Grover 118:620d28e7a1ba 66 /** Create an empty chain
Rohit Grover 118:620d28e7a1ba 67 *
Rohit Grover 118:620d28e7a1ba 68 * @param size (optional) Initial size of the chain
Rohit Grover 118:620d28e7a1ba 69 */
Rohit Grover 118:620d28e7a1ba 70 CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
Rohit Grover 118:620d28e7a1ba 71 /* empty */
Rohit Grover 118:620d28e7a1ba 72 }
Rohit Grover 118:620d28e7a1ba 73
Rohit Grover 118:620d28e7a1ba 74 virtual ~CallChainOfFunctionPointersWithContext() {
Rohit Grover 118:620d28e7a1ba 75 clear();
Rohit Grover 118:620d28e7a1ba 76 }
Rohit Grover 118:620d28e7a1ba 77
Rohit Grover 118:620d28e7a1ba 78 /** Add a function at the front of the chain
Rohit Grover 118:620d28e7a1ba 79 *
Rohit Grover 118:620d28e7a1ba 80 * @param function A pointer to a void function
Rohit Grover 118:620d28e7a1ba 81 *
Rohit Grover 118:620d28e7a1ba 82 * @returns
Rohit Grover 118:620d28e7a1ba 83 * The function object created for 'function'
Rohit Grover 118:620d28e7a1ba 84 */
Rohit Grover 118:620d28e7a1ba 85 pFunctionPointerWithContext_t add(void (*function)(ContextType context)) {
Rohit Grover 118:620d28e7a1ba 86 return common_add(new FunctionPointerWithContext<ContextType>(function));
Rohit Grover 118:620d28e7a1ba 87 }
Rohit Grover 118:620d28e7a1ba 88
Rohit Grover 118:620d28e7a1ba 89 /** Add a function at the front of the chain
Rohit Grover 118:620d28e7a1ba 90 *
Rohit Grover 118:620d28e7a1ba 91 * @param tptr pointer to the object to call the member function on
Rohit Grover 118:620d28e7a1ba 92 * @param mptr pointer to the member function to be called
Rohit Grover 118:620d28e7a1ba 93 *
Rohit Grover 118:620d28e7a1ba 94 * @returns
Rohit Grover 118:620d28e7a1ba 95 * The function object created for 'tptr' and 'mptr'
Rohit Grover 118:620d28e7a1ba 96 */
Rohit Grover 118:620d28e7a1ba 97 template<typename T>
Rohit Grover 118:620d28e7a1ba 98 pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) {
Rohit Grover 118:620d28e7a1ba 99 return common_add(new FunctionPointerWithContext<ContextType>(tptr, mptr));
Rohit Grover 118:620d28e7a1ba 100 }
Rohit Grover 118:620d28e7a1ba 101
Rohit Grover 118:620d28e7a1ba 102 /** Clear the call chain (remove all functions in the chain).
Rohit Grover 118:620d28e7a1ba 103 */
Rohit Grover 118:620d28e7a1ba 104 void clear(void) {
Rohit Grover 118:620d28e7a1ba 105 pFunctionPointerWithContext_t fptr = chainHead;
Rohit Grover 118:620d28e7a1ba 106 while (fptr) {
Rohit Grover 118:620d28e7a1ba 107 pFunctionPointerWithContext_t deadPtr = fptr;
Rohit Grover 118:620d28e7a1ba 108 fptr = deadPtr->getNext();
Rohit Grover 118:620d28e7a1ba 109 delete deadPtr;
Rohit Grover 118:620d28e7a1ba 110 }
Rohit Grover 118:620d28e7a1ba 111
Rohit Grover 118:620d28e7a1ba 112 chainHead = NULL;
Rohit Grover 118:620d28e7a1ba 113 }
Rohit Grover 118:620d28e7a1ba 114
Rohit Grover 118:620d28e7a1ba 115 bool hasCallbacksAttached(void) const {
Rohit Grover 118:620d28e7a1ba 116 return (chainHead != NULL);
Rohit Grover 118:620d28e7a1ba 117 }
Rohit Grover 118:620d28e7a1ba 118
Rohit Grover 118:620d28e7a1ba 119 /** Call all the functions in the chain in sequence
Rohit Grover 118:620d28e7a1ba 120 * @Note: the stack frames of all the callbacks within the chained
Rohit Grover 118:620d28e7a1ba 121 * FunctionPointers will stack up. Hopefully there won't be too many
Rohit Grover 118:620d28e7a1ba 122 * chained FunctionPointers.
Rohit Grover 118:620d28e7a1ba 123 */
Rohit Grover 118:620d28e7a1ba 124 void call(ContextType context) {
Rohit Grover 118:620d28e7a1ba 125 if (chainHead)
Rohit Grover 118:620d28e7a1ba 126 chainHead->call(context);
Rohit Grover 118:620d28e7a1ba 127 }
Rohit Grover 118:620d28e7a1ba 128
Rohit Grover 118:620d28e7a1ba 129 private:
Rohit Grover 118:620d28e7a1ba 130 pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) {
Rohit Grover 118:620d28e7a1ba 131 if (chainHead == NULL) {
Rohit Grover 118:620d28e7a1ba 132 chainHead = pf;
Rohit Grover 118:620d28e7a1ba 133 } else {
Rohit Grover 118:620d28e7a1ba 134 pf->chainAsNext(chainHead);
Rohit Grover 118:620d28e7a1ba 135 chainHead = pf;
Rohit Grover 118:620d28e7a1ba 136 }
Rohit Grover 118:620d28e7a1ba 137
Rohit Grover 118:620d28e7a1ba 138 return chainHead;
Rohit Grover 118:620d28e7a1ba 139 }
Rohit Grover 118:620d28e7a1ba 140
Rohit Grover 118:620d28e7a1ba 141 private:
Rohit Grover 118:620d28e7a1ba 142 pFunctionPointerWithContext_t chainHead;
Rohit Grover 118:620d28e7a1ba 143
Rohit Grover 118:620d28e7a1ba 144 /* disallow copy constructor and assignment operators */
Rohit Grover 118:620d28e7a1ba 145 private:
Rohit Grover 118:620d28e7a1ba 146 CallChainOfFunctionPointersWithContext(const CallChainOfFunctionPointersWithContext &);
Rohit Grover 118:620d28e7a1ba 147 CallChainOfFunctionPointersWithContext & operator = (const CallChainOfFunctionPointersWithContext &);
Rohit Grover 118:620d28e7a1ba 148 };
Rohit Grover 118:620d28e7a1ba 149
Rohit Grover 118:620d28e7a1ba 150 } // namespace mbed
Rohit Grover 118:620d28e7a1ba 151
Rohit Grover 118:620d28e7a1ba 152 #endif
Rohit Grover 118:620d28e7a1ba 153