Diff: public/BLE.h

Revision:

540:1fb1e0b809eb

Parent:

539:0b6e82025358

Child:

541:aa30f63e7b3f

--- a/public/BLE.h	Fri Jun 19 15:52:08 2015 +0100
+++ b/public/BLE.h	Fri Jun 19 15:52:08 2015 +0100
@@ -85,6 +85,17 @@
         return transport->getGattServer();
     }
 
+    /*
+     * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
+     * functionality requires going through this accessor.
+     */
+    const GattClient& gattClient() const {
+        return transport->getGattClient();
+    }
+    GattClient& gattClient() {
+        return transport->getGattClient();
+    }
+
     /**
      * Yield control to the BLE stack or to other tasks waiting for events. This
      * is a sleep function which will return when there is an application
@@ -116,6 +127,68 @@
                                    Gap::SecurityIOCapabilities_t iocaps        = Gap::IO_CAPS_NONE,
                                    const Gap::Passkey_t          passkey       = NULL);
 
+    /**
+     * Setup a callback for when the security setup procedure (key generation
+     * and exchange) for a link has started. This will be skipped for bonded
+     * devices. The callback is passed in parameters received from the peer's
+     * security request: bool allowBonding, bool requireMITM, and
+     * SecurityIOCapabilities_t.
+     */
+    void onSecuritySetupInitiated(Gap::SecuritySetupInitiatedCallback_t callback);
+
+    /**
+     * Setup a callback for when the security setup procedure (key generation
+     * and exchange) for a link has completed. This will be skipped for bonded
+     * devices. The callback is passed in the success/failure status of the
+     * security setup procedure.
+     */
+    void onSecuritySetupCompleted(Gap::SecuritySetupCompletedCallback_t callback);
+
+    /**
+     * Setup a callback for when a link with the peer is secured. For bonded
+     * devices, subsequent reconnections with bonded peer will result only in
+     * this callback when the link is secured and setup procedures will not
+     * occur unless the bonding information is either lost or deleted on either
+     * or both sides. The callback is passed in a Gap::SecurityMode_t according
+     * to the level of security in effect for the secured link.
+     */
+    void onLinkSecured(Gap::LinkSecuredCallback_t callback);
+
+    /**
+     * Setup a callback for successful bonding; i.e. that link-specific security
+     * context is stored persistently for a peer device.
+     */
+    void onSecurityContextStored(Gap::HandleSpecificEvent_t callback);
+
+    /**
+     * Setup a callback for when the passkey needs to be displayed on a
+     * peripheral with DISPLAY capability. This happens when security is
+     * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey)
+     * needs to be exchanged between the peers to authenticate the connection
+     * attempt.
+     */
+    void onPasskeyDisplay(Gap::PasskeyDisplayCallback_t callback);
+
+    /**
+     * Get the security status of a connection.
+     *
+     * @param[in]  connectionHandle   Handle to identify the connection.
+     * @param[out] securityStatusP    security status.
+     *
+     * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
+     */
+    ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, Gap::LinkSecurityStatus_t *securityStatusP);
+
+    /**
+     * Delete all peer device context and all related bonding information from
+     * the database within the security manager.
+     *
+     * @retval BLE_ERROR_NONE             On success, else an error code indicating reason for failure.
+     * @retval BLE_ERROR_INVALID_STATE    If the API is called without module initialization and/or
+     *                                    application registration.
+     */
+    ble_error_t purgeAllBondingState(void);
+
     /*
      * Deprecation alert!
      * All of the following are deprecated and may be dropped in a future
@@ -848,95 +921,6 @@
         gap().getPermittedTxPowerValues(valueArrayPP, countP);
     }
 
-    /* APIs to set GAP callbacks. */
-    void onTimeout(Gap::EventCallback_t timeoutCallback);
-
-    void onConnection(Gap::ConnectionEventCallback_t connectionCallback);
-    /**
-     * Used to setup a callback for GAP disconnection.
-     */
-    void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback);
-
-    /**
-     * Append to a chain of callbacks to be invoked upon disconnection; these
-     * callbacks receive no context and are therefore different from the
-     * onDisconnection callback.
-     */
-    template<typename T>
-    void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void));
-
-    /**
-     * Add a callback for the GATT event DATA_SENT (which is triggered when
-     * updates are sent out by GATT in the form of notifications).
-     *
-     * @Note: it is possible to chain together multiple onDataSent callbacks
-     * (potentially from different modules of an application) to receive updates
-     * to characteristics.
-     *
-     * @Note: it is also possible to setup a callback into a member function of
-     * some object.
-     */
-    void onDataSent(void (*callback)(unsigned count));
-    template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count));
-
-    /**
-     * Setup a callback for when a characteristic has its value updated by a
-     * client.
-     *
-     * @Note: 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.
-     *
-     * @Note: it is also possible to setup a callback into a member function of
-     * some object.
-     */
-    void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP));
-    template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context));
-
-    /**
-     * Setup a callback for when a characteristic is being read by a client.
-     *
-     * @Note: this functionality may not be available on all underlying stacks.
-     * You could use GattCharacteristic::setReadAuthorizationCallback() as an
-     * alternative.
-     *
-     * @Note: it is possible to chain together multiple onDataRead callbacks
-     * (potentially from different modules of an application) to receive updates
-     * to characteristics. Services may add their own onDataRead callbacks
-     * behind the scenes to trap interesting events.
-     *
-     * @Note: it is also possible to setup a callback into a member function of
-     * some object.
-     *
-     * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
-     *         else BLE_ERROR_NONE.
-     */
-    ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP));
-    template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context));
-
-    void onUpdatesEnabled(GattServer::EventCallback_t callback);
-    void onUpdatesDisabled(GattServer::EventCallback_t callback);
-    void onConfirmationReceived(GattServer::EventCallback_t callback);
-
-    /**
-     * Radio Notification is a feature that enables ACTIVE and INACTIVE
-     * (nACTIVE) signals from the stack that notify the application when the
-     * radio is in use. The signal is sent using software interrupt.
-     *
-     * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
-     * signal is sent at the end of the Radio Event. These signals can be used
-     * by the application programmer to synchronize application logic with radio
-     * activity. For example, the ACTIVE signal can be used to shut off external
-     * devices to manage peak current drawn during periods when the radio is on,
-     * or to trigger sensor data collection for transmission in the Radio Event.
-     *
-     * @param callback
-     *          The application handler to be invoked in response to a radio
-     *          ACTIVE/INACTIVE event.
-     */
-    void onRadioNotification(Gap::RadioNotificationEventCallback_t callback);
-
     /**
      * Add a service declaration to the local server ATT table. Also add the
      * characteristics contained within.
@@ -1069,139 +1053,93 @@
         return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
     }
 
-    /**
-     * Setup a callback for when the security setup procedure (key generation
-     * and exchange) for a link has started. This will be skipped for bonded
-     * devices. The callback is passed in parameters received from the peer's
-     * security request: bool allowBonding, bool requireMITM, and
-     * SecurityIOCapabilities_t.
-     */
-    void onSecuritySetupInitiated(Gap::SecuritySetupInitiatedCallback_t callback);
+    void onTimeout(Gap::EventCallback_t timeoutCallback);
 
+    void onConnection(Gap::ConnectionEventCallback_t connectionCallback);
     /**
-     * Setup a callback for when the security setup procedure (key generation
-     * and exchange) for a link has completed. This will be skipped for bonded
-     * devices. The callback is passed in the success/failure status of the
-     * security setup procedure.
+     * Used to setup a callback for GAP disconnection.
      */
-    void onSecuritySetupCompleted(Gap::SecuritySetupCompletedCallback_t callback);
-
-    /**
-     * Setup a callback for when a link with the peer is secured. For bonded
-     * devices, subsequent reconnections with bonded peer will result only in
-     * this callback when the link is secured and setup procedures will not
-     * occur unless the bonding information is either lost or deleted on either
-     * or both sides. The callback is passed in a Gap::SecurityMode_t according
-     * to the level of security in effect for the secured link.
-     */
-    void onLinkSecured(Gap::LinkSecuredCallback_t callback);
+    void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback);
 
     /**
-     * Setup a callback for successful bonding; i.e. that link-specific security
-     * context is stored persistently for a peer device.
+     * Append to a chain of callbacks to be invoked upon disconnection; these
+     * callbacks receive no context and are therefore different from the
+     * onDisconnection callback.
      */
-    void onSecurityContextStored(Gap::HandleSpecificEvent_t callback);
-
-    /**
-     * Setup a callback for when the passkey needs to be displayed on a
-     * peripheral with DISPLAY capability. This happens when security is
-     * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey)
-     * needs to be exchanged between the peers to authenticate the connection
-     * attempt.
-     */
-    void onPasskeyDisplay(Gap::PasskeyDisplayCallback_t callback);
+    template<typename T>
+    void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void));
 
     /**
-     * Get the security status of a connection.
+     * Add a callback for the GATT event DATA_SENT (which is triggered when
+     * updates are sent out by GATT in the form of notifications).
      *
-     * @param[in]  connectionHandle   Handle to identify the connection.
-     * @param[out] securityStatusP    security status.
+     * @Note: it is possible to chain together multiple onDataSent callbacks
+     * (potentially from different modules of an application) to receive updates
+     * to characteristics.
      *
-     * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
+     * @Note: it is also possible to setup a callback into a member function of
+     * some object.
      */
-    ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, Gap::LinkSecurityStatus_t *securityStatusP);
-
-    /**
-     * Delete all peer device context and all related bonding information from
-     * the database within the security manager.
-     *
-     * @retval BLE_ERROR_NONE             On success, else an error code indicating reason for failure.
-     * @retval BLE_ERROR_INVALID_STATE    If the API is called without module initialization and/or
-     *                                    application registration.
-     */
-    ble_error_t purgeAllBondingState(void);
+    void onDataSent(void (*callback)(unsigned count));
+    template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count));
 
     /**
-     * Launch service discovery. Once launched, service discovery will remain
-     * active with callbacks being issued back into the application for matching
-     * services/characteristics. isServiceDiscoveryActive() can be used to
-     * determine status; and a termination callback (if setup) will be invoked
-     * at the end. Service discovery can be terminated prematurely if needed
-     * using terminateServiceDiscovery().
+     * Setup a callback for when a characteristic has its value updated by a
+     * client.
      *
-     * @param  connectionHandle
-     *           Handle for the connection with the peer.
-     * @param  sc
-     *           This is the application callback for matching service. Taken as
-     *           NULL by default. Note: service discovery may still be active
-     *           when this callback is issued; calling asynchronous BLE-stack
-     *           APIs from within this application callback might cause the
-     *           stack to abort service discovery. If this becomes an issue, it
-     *           may be better to make local copy of the discoveredService and
-     *           wait for service discovery to terminate before operating on the
-     *           service.
-     * @param  cc
-     *           This is the application callback for matching characteristic.
-     *           Taken as NULL by default. Note: service discovery may still be
-     *           active when this callback is issued; calling asynchronous
-     *           BLE-stack APIs from within this application callback might cause
-     *           the stack to abort service discovery. If this becomes an issue,
-     *           it may be better to make local copy of the discoveredCharacteristic
-     *           and wait for service discovery to terminate before operating on the
-     *           characteristic.
-     * @param  matchingServiceUUID
-     *           UUID based filter for specifying a service in which the application is
-     *           interested. By default it is set as the wildcard UUID_UNKNOWN,
-     *           in which case it matches all services. If characteristic-UUID
-     *           filter (below) is set to the wildcard value, then a service
-     *           callback will be invoked for the matching service (or for every
-     *           service if the service filter is a wildcard).
-     * @param  matchingCharacteristicUUIDIn
-     *           UUID based filter for specifying characteristic in which the application
-     *           is interested. By default it is set as the wildcard UUID_UKNOWN
-     *           to match against any characteristic. If both service-UUID
-     *           filter and characteristic-UUID filter are used with non- wildcard
-     *           values, then only a single characteristic callback is
-     *           invoked for the matching characteristic.
+     * @Note: 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.
      *
-     * @Note     Using wildcard values for both service-UUID and characteristic-
-     *           UUID will result in complete service discovery--callbacks being
-     *           called for every service and characteristic.
-     *
-     * @return
-     *           BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
+     * @Note: it is also possible to setup a callback into a member function of
+     * some object.
      */
-    ble_error_t launchServiceDiscovery(Gap::Handle_t                               connectionHandle,
-                                       ServiceDiscovery::ServiceCallback_t         sc = NULL,
-                                       ServiceDiscovery::CharacteristicCallback_t  cc = NULL,
-                                       const UUID                                 &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
-                                       const UUID                                 &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN));
+    void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP));
+    template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context));
 
     /**
-     * Setup callback for when serviceDiscovery terminates.
+     * Setup a callback for when a characteristic is being read by a client.
+     *
+     * @Note: this functionality may not be available on all underlying stacks.
+     * You could use GattCharacteristic::setReadAuthorizationCallback() as an
+     * alternative.
+     *
+     * @Note: it is possible to chain together multiple onDataRead callbacks
+     * (potentially from different modules of an application) to receive updates
+     * to characteristics. Services may add their own onDataRead callbacks
+     * behind the scenes to trap interesting events.
+     *
+     * @Note: it is also possible to setup a callback into a member function of
+     * some object.
+     *
+     * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
+     *         else BLE_ERROR_NONE.
      */
-    void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback);
+    ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP));
+    template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context));
+
+    void onUpdatesEnabled(GattServer::EventCallback_t callback);
+    void onUpdatesDisabled(GattServer::EventCallback_t callback);
+    void onConfirmationReceived(GattServer::EventCallback_t callback);
 
     /**
-     * Is service-discovery currently active?
+     * Radio Notification is a feature that enables ACTIVE and INACTIVE
+     * (nACTIVE) signals from the stack that notify the application when the
+     * radio is in use. The signal is sent using software interrupt.
+     *
+     * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
+     * signal is sent at the end of the Radio Event. These signals can be used
+     * by the application programmer to synchronize application logic with radio
+     * activity. For example, the ACTIVE signal can be used to shut off external
+     * devices to manage peak current drawn during periods when the radio is on,
+     * or to trigger sensor data collection for transmission in the Radio Event.
+     *
+     * @param callback
+     *          The application handler to be invoked in response to a radio
+     *          ACTIVE/INACTIVE event.
      */
-    bool isServiceDiscoveryActive(void);
-
-    /**
-     * Terminate an ongoing service-discovery. This should result in an
-     * invocation of the TerminationCallback if service-discovery is active.
-     */
-    void terminateServiceDiscovery(void);
+    void onRadioNotification(Gap::RadioNotificationEventCallback_t callback);
 
 public:
     BLE() : transport(createBLEInstance()) {
@@ -1347,39 +1285,4 @@
     return gap().purgeAllBondingState();
 }
 
-inline ble_error_t
-BLE::launchServiceDiscovery(Gap::Handle_t                               connectionHandle,
-                            ServiceDiscovery::ServiceCallback_t         sc,
-                            ServiceDiscovery::CharacteristicCallback_t  cc,
-                            const UUID                                 &matchingServiceUUID,
-                            const UUID                                 &matchingCharacteristicUUID)
-{
-    return transport->getGattClient().launchServiceDiscovery(connectionHandle, sc, cc, matchingServiceUUID, matchingCharacteristicUUID);
-}
-
-inline void
-BLE::onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback)
-{
-    transport->getGattClient().onServiceDiscoveryTermination(callback);
-}
-
-/**
- * Is service-discovery currently active?
- */
-inline bool
-BLE::isServiceDiscoveryActive(void)
-{
-    return transport->getGattClient().isServiceDiscoveryActive();
-}
-
-/**
- * Terminate an ongoing service-discovery. This should result in an
- * invocation of the TerminationCallback if service-discovery is active.
- */
-inline void
-BLE::terminateServiceDiscovery(void)
-{
-    transport->getGattClient().terminateServiceDiscovery();
-}
-
 #endif // ifndef __BLE_H__
\ No newline at end of file