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 __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
00018 #define __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
00019 
00020 #include "FunctionPointerWithContext.h"
00021 
00022 class DiscoveredCharacteristic;                         // forward declaration
00023 class DiscoveredCharacteristicDescriptor;               // forward declaration
00024 
00025 /**
00026  * @brief Contain all definitions of callbacks and callbacks parameters types
00027  * related to characteristic descriptor discovery.
00028  *
00029  * @details This class act like a namespace for characteristic descriptor discovery
00030  * types. It act like ServiceDiscovery by providing callbacks and callbacks
00031  * parameters types related to the characteristic descriptor discovery process but
00032  * contrary to ServiceDiscovery class, it does not force the porter to use a
00033  * specific interface for the characteristic descriptor discovery process.
00034  */
00035 class CharacteristicDescriptorDiscovery {
00036 public:
00037     /**
00038      * @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t.
00039      * @details Every time a characteristic descriptor has been discovered, the callback
00040      * registered for the discovery operation through GattClient::discoverCharacteristicDescriptors
00041      * or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter.
00042      *
00043      */
00044     struct DiscoveryCallbackParams_t {
00045         /**
00046          * The characteristic owning the DiscoveredCharacteristicDescriptor
00047          */
00048         const DiscoveredCharacteristic& characteristic;
00049 
00050         /**
00051          * The characteristic descriptor discovered
00052          */
00053         const DiscoveredCharacteristicDescriptor& descriptor;
00054     };
00055 
00056     /**
00057      * @brief Parameter type of CharacteristicDescriptorDiscovery::TerminationCallback_t.
00058      * @details Once a characteristic descriptor discovery process terminate, the termination
00059      * callback registered for the discovery operation through
00060      * GattClient::discoverCharacteristicDescriptors or DiscoveredCharacteristic::discoverDescriptors
00061      * will be called with this parameter.
00062      */
00063     struct TerminationCallbackParams_t {
00064         /**
00065          * The characteristic for which the descriptors has been discovered
00066          */
00067         const DiscoveredCharacteristic& characteristic;
00068 
00069         /**
00070          * status of the discovery operation
00071          */
00072         ble_error_t status;
00073     };
00074 
00075     /**
00076      * @brief Callback type for when a matching characteristic descriptor is found during
00077      * characteristic descriptor discovery.
00078      *
00079      * @param param A pointer to a DiscoveryCallbackParams_t object which will remain
00080      * valid for the lifetime of the callback. Memory for this object is owned by
00081      * the BLE_API eventing framework. The application can safely make a persistent
00082      * shallow-copy of this object in order to work with the service beyond the
00083      * callback.
00084      */
00085     typedef FunctionPointerWithContext<const DiscoveryCallbackParams_t*> DiscoveryCallback_t;
00086 
00087     /**
00088      * @brief Callback type for when characteristic descriptor discovery terminates.
00089      *
00090      * @param param A pointer to a TerminationCallbackParams_t object which will remain
00091      * valid for the lifetime of the callback. Memory for this object is owned by
00092      * the BLE_API eventing framework. The application can safely make a persistent
00093      * shallow-copy of this object in order to work with the service beyond the
00094      * callback.
00095      */
00096     typedef FunctionPointerWithContext<const TerminationCallbackParams_t*> TerminationCallback_t;
00097 };
00098 
00099 #endif // ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__