CharacteristicDescriptorDiscovery.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 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 MBED_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
00018 #define MBED_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
00019 
00020 #include "FunctionPointerWithContext.h "
00021 
00022 class DiscoveredCharacteristic;                         // forward declaration
00023 class DiscoveredCharacteristicDescriptor;               // forward declaration
00024 
00025 /**
00026  * @addtogroup ble
00027  * @{
00028  * @addtogroup gatt
00029  * @{
00030  */
00031 
00032 /**
00033  * Definitions of events and event handlers that the characteristic descriptor
00034  * discovery procedure uses.
00035  *
00036  * This class acts like a namespace for characteristic descriptor discovery
00037  * types. Like ServiceDiscovery, it provides callbacks and callbacks parameters
00038  * types related to the characteristic descriptor discovery process, but contrary
00039  * to the ServiceDiscovery class, it does not force the porter to use a specific
00040  * interface for the characteristic descriptor discovery process.
00041  */
00042 class CharacteristicDescriptorDiscovery {
00043 public:
00044     /**
00045      * Characteristic descriptor discovered event.
00046      *
00047      * When a characteristic descriptor has been discovered, the callback
00048      * registered for the discovery operation through
00049      * GattClient::discoverCharacteristicDescriptors or
00050      * DiscoveredCharacteristic::discoverDescriptors is called with an instance
00051      * of this type.
00052      *
00053      * The values reported to the user are the descriptor discovered and the
00054      * characteristic owning that descriptor.
00055      *
00056      * @see GattClient::discoverCharacteristicDescriptors
00057      * DiscoveredCharacteristic::discoverDescriptors
00058      */
00059     struct DiscoveryCallbackParams_t {
00060         /**
00061          * Characteristic owning the descriptor discovered.
00062          */
00063         const DiscoveredCharacteristic &characteristic;
00064 
00065         /**
00066          * Characteristic descriptor discovered.
00067          */
00068         const DiscoveredCharacteristicDescriptor &descriptor;
00069     };
00070 
00071     /**
00072      * Characteristic descriptor discovery ended event.
00073      *
00074      * When the characteristic descriptor discovery process ends, the
00075      * termination callback registered for the discovery operation through
00076      * GattClient::discoverCharacteristicDescriptors or
00077      * DiscoveredCharacteristic::discoverDescriptors will be called with an
00078      * instance of this type.
00079      *
00080      * @see GattClient::discoverCharacteristicDescriptors
00081      * DiscoveredCharacteristic::discoverDescriptors
00082      */
00083     struct TerminationCallbackParams_t {
00084         /**
00085          * Characteristic for which descriptors has been discovered.
00086          */
00087         const DiscoveredCharacteristic& characteristic;
00088 
00089         /**
00090          * Status of the discovery operation.
00091          */
00092         ble_error_t status;
00093 
00094         /**
00095          * Error code associated with the status if any.
00096          */
00097         uint8_t error_code;
00098     };
00099 
00100     /**
00101      * Characteristic descriptor discovered event handler.
00102      *
00103      * As a parameter, it expects a pointer to a DiscoveryCallbackParams_t instance.
00104      *
00105      * @note The object passed in parameter will remain valid for the lifetime
00106      * of the callback. The BLE_API eventing framework owns memory for this
00107      * object. The application can safely make a persistent shallow-copy of
00108      * this object to work with the service beyond the callback.
00109      *
00110      * @see DiscoveryCallbackParams_t
00111      * GattClient::discoverCharacteristicDescriptors
00112      * DiscoveredCharacteristic::discoverDescriptors
00113      */
00114     typedef FunctionPointerWithContext<const DiscoveryCallbackParams_t*> 
00115         DiscoveryCallback_t;
00116 
00117     /**
00118      * Handler of Characteristic descriptor discovery ended event.
00119      *
00120      * As a parameter, it expects a pointer to a TerminationCallbackParams_t instance.
00121      *
00122      * @note The object passed in parameter will remain valid for the lifetime
00123      * of the callback. The BLE_API eventing framework owns the memory for this
00124      * object. The application can safely make a persistent shallow-copy of
00125      * this object to work with the service beyond the callback.
00126      *
00127      * @see TerminationCallbackParams_t
00128      * GattClient::discoverCharacteristicDescriptors
00129      * DiscoveredCharacteristic::discoverDescriptors
00130      */
00131     typedef FunctionPointerWithContext<const TerminationCallbackParams_t*> 
00132         TerminationCallback_t;
00133 };
00134 
00135 /**
00136  * @}
00137  * @}
00138  */
00139 
00140 #endif // ifndef MBED_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__