Mistake on this page?
Report an issue in GitHub or email us
BLEInstanceBase.h
Go to the documentation of this file.
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * @file
19  */
20 
21 #ifndef MBED_BLE_DEVICE_INSTANCE_BASE__
22 #define MBED_BLE_DEVICE_INSTANCE_BASE__
23 
24 #include "ble/BLE.h"
25 #include "ble/Gap.h"
26 #include "ble/SecurityManager.h"
27 #include "ble/GattServer.h"
28 #include "ble/GattClient.h"
29 
30 
31 
32 /**
33  * @addtogroup ble
34  * @{
35  * @addtogroup porting
36  * @{
37  */
38 
39 /**
40  * Private interface used to implement the BLE class.
41  *
42  * The BLE class delegates all its abstract operations to an instance of this
43  * abstract class, which every vendor port of Mbed BLE shall implement.
44  *
45  * The vendor port shall also define an implementation of the freestanding function
46  * createBLEInstance(). The BLE API uses this singleton function to gain
47  * access to a concrete implementation of this class defined in the vendor port.
48  *
49  * @attention This class is part of the porting API and is not meant to be used
50  * by end users of BLE API.
51  *
52  * @see BLE
53  */
55 {
56 public:
57  /**
58  * Base constructor.
59  */
61 
62  /**
63  * Virtual destructor of the interface.
64  */
65  virtual ~BLEInstanceBase();
66 
67  /**
68  * Process ALL pending events living in the vendor BLE subsystem.
69  *
70  * Return once all pending events have been consumed.
71  *
72  * @see BLE::processEvents()
73  */
74  virtual void processEvents() = 0;
75 
76  /**
77  * Signal to BLE that events needing processing are available.
78  *
79  * The vendor port shall call this function whenever there are events
80  * ready to be processed in the internal stack or BLE subsystem. As a result
81  * of this call, the callback registered by the end user via
82  * BLE::onEventsToProcess will be invoked.
83  *
84  * @param[in] id: Identifier of the BLE instance, which does have events to
85  * ready to be processed.
86  */
88 
89  /**
90  * Start the initialization of the vendor BLE subsystem.
91  *
92  * Calls to this function are initiated by BLE::init, instanceID identify
93  * the BLE instance which issue that call while the initCallback is used to
94  * signal asynchronously the completion of the initialization process.
95  *
96  * @param[in] instanceID Identifier of the BLE instance requesting
97  * initialization.
98  * @param[in] initCallback Callback which the vendor port shall invoke
99  * when the initialization completes.
100  *
101  * This is an optional parameter set to NULL when not supplied.
102  *
103  * @return BLE_ERROR_NONE if the initialization procedure started
104  * successfully.
105  *
106  * @post initCallback shall be invoked upon completion of the initialization
107  * process.
108  *
109  * @post hasInitialized() shall return false until the initialization is
110  * complete, and it shall return true after succesful completion of the
111  * initialization process.
112  *
113  * @see BLE::init()
114  */
115  virtual ble_error_t init(
116  BLE::InstanceID_t instanceID,
118  ) = 0;
119 
120  /**
121  * Check whether the vendor BLE subsystem has been initialized or not.
122  *
123  * @return true if the initialization has completed for the vendor BLE
124  * subsystem.
125  *
126  * @note this function is invoked by BLE::hasInitialized()
127  *
128  * @see BLE::init() BLE::hasInitialized()
129  */
130  virtual bool hasInitialized(void) const = 0;
131 
132  /**
133  * Shutdown the vendor BLE subsystem.
134  *
135  * This operation includes purging the stack of GATT and GAP state and
136  * clearing all state from other BLE components, such as the SecurityManager.
137  * Clearing all states may be realized by a call to Gap::reset(),
138  * GattClient::reset(), GattServer::reset() and SecurityManager::reset().
139  *
140  * BLE::init() must be called afterward to reinstantiate services and GAP
141  * state.
142  *
143  * @return BLE_ERROR_NONE if the underlying stack and all other services of
144  * the BLE API were shut down correctly.
145  *
146  * @post hasInitialized() shall return false.
147  *
148  * @note This function is invoked by BLE::shutdown().
149  *
150  * @see BLE::shutdown() BLE::init() BLE::hasInitialized() Gap::reset()
151  * GattClient::reset() GattServer::reset() SecurityManager::reset() .
152  */
153  virtual ble_error_t shutdown(void) = 0;
154 
155  /**
156  * Fetches a NULL terminated string representation of the underlying BLE
157  * vendor subsystem.
158  *
159  * @return A pointer to the NULL terminated string representation of the
160  * underlying BLE stack's version.
161  *
162  * @see BLE::getVersion()
163  */
164  virtual const char *getVersion(void) = 0;
165 
166  /**
167  * Accessor to the vendor implementation of the Gap interface.
168  *
169  * @return A reference to a Gap object associated to this BLEInstanceBase
170  * instance.
171  *
172  * @see BLE::gap() Gap
173  */
174  virtual Gap &getGap(void) = 0;
175 
176  /**
177  * Const alternative to getGap().
178  *
179  * @return A const reference to a Gap object associated to this
180  * BLEInstanceBase instance.
181  *
182  * @see BLE::gap() Gap
183  */
184  virtual const Gap &getGap(void) const = 0;
185 
186 
187 #if BLE_FEATURE_GATT_SERVER
188  /**
189  * Accessor to the vendor implementation of the GattServer interface.
190  *
191  * @return A reference to a GattServer object associated to this
192  * BLEInstanceBase instance.
193  *
194  * @see BLE::gattServer() GattServer
195  */
196  virtual GattServer &getGattServer(void) = 0;
197 
198  /**
199  * A const alternative to getGattServer().
200  *
201  * @return A const reference to a GattServer object associated to this
202  * BLEInstanceBase instance.
203  *
204  * @see BLE::gattServer() GattServer
205  */
206  virtual const GattServer &getGattServer(void) const = 0;
207 #endif // BLE_FEATURE_GATT_SERVER
208 
209 #if BLE_FEATURE_GATT_CLIENT
210  /**
211  * Accessor to the vendor implementation of the GattClient interface.
212  *
213  * @return A reference to a GattClient object associated to this
214  * BLEInstanceBase instance.
215  *
216  * @see BLE::gattClient() GattClient
217  */
218  virtual GattClient &getGattClient(void) = 0;
219 #endif
220 
221 #if BLE_FEATURE_SECURITY
222  /**
223  * Accessor to the vendor implementation of the SecurityManager interface.
224  *
225  * @return A reference to a SecurityManager object associated to this
226  * BLEInstanceBase instance.
227  *
228  * @see BLE::securityManager() SecurityManager
229  */
230  virtual SecurityManager &getSecurityManager(void) = 0;
231 
232  /**
233  * A const alternative to getSecurityManager().
234  *
235  * @return A const reference to a SecurityManager object associated to this
236  * BLEInstancebase instance.
237  *
238  * @see BLE::securityManager() SecurityManager
239  */
240  virtual const SecurityManager &getSecurityManager(void) const = 0;
241 #endif // BLE_FEATURE_SECURITY
242 
243  /**
244  * Process pending events present in the vendor subsystem; then, put the MCU
245  * to sleep until an external source wakes it up.
246  *
247  * @attention This function is deprecated in the BLE class. It will be
248  * removed from this interface once it is removed from BLE.
249  *
250  * @see BLE::waitForEvent() BLE::processEvents()
251  */
252  virtual void waitForEvent(void) = 0;
253 
254 private:
255  // this class is not a value type.
256  // prohibit copy construction and copy assignement
258  BLEInstanceBase &operator=(const BLEInstanceBase&);
259 };
260 
261 /**
262  * Return the instance of the vendor implementation of BLEInstanceBase.
263  *
264  * @attention Contrary to its name, this function does not return a new instance
265  * at each call. It rather acts like an accessor to a singleton.
266  *
267  * @attention The vendor library must provide an implementation for this function
268  * library. Otherwise, there will be a linker error.
269  */
270 extern BLEInstanceBase *createBLEInstance(void);
271 
272 /**
273  * @}
274  * @}
275  */
276 
277 #endif // ifndef MBED_BLE_DEVICE_INSTANCE_BASE__
Function like object adapter over freestanding and member functions.
Private interface used to implement the BLE class.
virtual void processEvents()=0
Process ALL pending events living in the vendor BLE subsystem.
virtual const char * getVersion(void)=0
Fetches a NULL terminated string representation of the underlying BLE vendor subsystem.
virtual bool hasInitialized(void) const =0
Check whether the vendor BLE subsystem has been initialized or not.
Define device discovery, connection and link management procedures.
Definition: Gap.h:52
unsigned InstanceID_t
Opaque type used to store the ID of a BLE instance.
Definition: BLE.h:144
Define procedures required for interacting with a distant GATT server.
Definition: GattClient.h:89
virtual GattClient & getGattClient(void)=0
Accessor to the vendor implementation of the GattClient interface.
Construct and operates a GATT server.
Definition: GattServer.h:98
virtual ~BLEInstanceBase()
Virtual destructor of the interface.
virtual ble_error_t shutdown(void)=0
Shutdown the vendor BLE subsystem.
BLEInstanceBase * createBLEInstance(void)
Return the instance of the vendor implementation of BLEInstanceBase.
virtual ble_error_t init(BLE::InstanceID_t instanceID, FunctionPointerWithContext< BLE::InitializationCompleteCallbackContext * > initCallback)=0
Start the initialization of the vendor BLE subsystem.
virtual GattServer & getGattServer(void)=0
Accessor to the vendor implementation of the GattServer interface.
virtual void waitForEvent(void)=0
Process pending events present in the vendor subsystem; then, put the MCU to sleep until an external ...
virtual Gap & getGap(void)=0
Accessor to the vendor implementation of the Gap interface.
virtual SecurityManager & getSecurityManager(void)=0
Accessor to the vendor implementation of the SecurityManager interface.
BLEInstanceBase()
Base constructor.
void signalEventsToProcess(BLE::InstanceID_t id)
Signal to BLE that events needing processing are available.
ble_error_t
Error codes for the BLE API.
Definition: blecommon.h:147
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.